---
title: 프로젝트 구조
description: Astro 프로젝트의 기본 파일 구조 소개
i18nReady: true
---
import { FileTree } from '@astrojs/starlight/components';

`create astro` CLI 마법사로 생성된 새 Astro 프로젝트에는 이미 일부 파일과 폴더가 포함되어 있습니다. 다른 파일들은 사용자가 직접 만들어 Astro의 기존 파일 구조에 추가해야 합니다.

Astro 프로젝트의 구성 방식과 새 프로젝트에서 찾을 수 있는 몇 가지 파일은 다음과 같습니다.

## 디렉터리 및 파일

Astro는 프로젝트에 대해 의견이 담긴 폴더 레이아웃을 활용합니다. 모든 Astro 프로젝트 루트에는 다음 디렉터리와 파일이 포함되어야 합니다.

- `src/*` - 프로젝트 소스 코드 (컴포넌트, 페이지, 스타일, 이미지 등)
- `public/*` - 코드 외 처리되지 않는 자산 (글꼴, 아이콘 등)
- `package.json` - 프로젝트 매니페스트
- `astro.config.mjs` - Astro 구성 파일 (권장)
- `tsconfig.json` - TypeScript 구성 파일 (권장)

### 프로젝트 트리 예시

일반적인 Astro 프로젝트 디렉터리는 다음과 같습니다.

<FileTree>
- public/
  - robots.txt
  - favicon.svg
  - my-cv.pdf
- src/
    - blog/
      - post1.md
      - post2.md
      - post3.md
  - components/
    - Header.astro
    - Button.jsx
  - images/
    - image1.jpg
    - image2.jpg
    - image3.jpg
  - layouts/
    - PostLayout.astro
  - pages/
    - posts/
      - [post].astro
    - about.astro
    - **index.astro**
    - rss.xml.js
  - styles/
    - global.css
  - content.config.ts
- astro.config.mjs
- package.json
- tsconfig.json
</FileTree>

### `src/`

`src/` 폴더는 대부분의 프로젝트 소스 코드가 위치하는 곳입니다. 여기에는 다음이 포함됩니다.

- [페이지](/ko/basics/astro-pages/)
- [레이아웃](/ko/basics/layouts/)
- [Astro 컴포넌트](/ko/basics/astro-components/)
- [UI 프레임워크 컴포넌트 (React 등)](/ko/guides/framework-components/)
- [스타일 (CSS, Sass)](/ko/guides/styling/)
- [Markdown](/ko/guides/markdown-content/)
- [Astro에 의해 최적화되고 처리될 이미지](/ko/guides/images/)

Astro는 `src/` 파일을 처리, 최적화 및 번들링하여 브라우저로 전송되는 최종 웹사이트를 만듭니다. 정적인 `public/` 디렉터리와 달리 `src/` 파일은 Astro에 의해 빌드되고 처리됩니다.

일부 파일 (예: Astro 컴포넌트)은 작성된 그대로 브라우저로 전송되지 않고 대신 정적 HTML로 렌더링됩니다. 다른 파일 (예: CSS)은 브라우저로 전송되지만 성능을 위해 최적화되거나 다른 CSS 파일과 함께 번들링될 수 있습니다.

:::tip
이 가이드에서는 Astro 커뮤니티에서 사용되는 몇 가지 일반적인 규칙을 설명하지만, Astro에서 예약된 유일한 디렉터리는 `src/pages/`입니다. 다른 모든 디렉터리는 사용자에게 가장 적합한 방식으로 이름을 바꾸고 재구성할 수 있습니다.
:::

### `src/pages`

사이트의 페이지 경로는 이 디렉터리에 [지원되는 파일 형식](/ko/basics/astro-pages/#지원되는-페이지-파일)을 추가하여 생성됩니다.

:::caution
`src/pages`는 Astro 프로젝트의 **필수** 하위 디렉터리입니다. 이 디렉터리가 없으면 사이트에 페이지나 경로가 없습니다!
:::

### `src/components`

**컴포넌트**는 HTML 페이지를 위한 재사용 가능한 코드 단위입니다. [Astro 컴포넌트](/ko/basics/astro-components/) 또는 React나 Vue와 같은 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/)일 수 있습니다. 이 폴더에 모든 프로젝트 컴포넌트를 함께 그룹화하고 정리하는 것이 일반적입니다.

Astro 프로젝트에서 흔히 사용되는 규칙이지만 필수는 아닙니다. 원하는 방식으로 컴포넌트를 구성해도 괜찮습니다!

### `src/layouts`

[레이아웃](/ko/basics/layouts/)은 하나 이상의 [페이지](/ko/basics/astro-pages/)에서 공유하는 UI 구조를 정의하는 Astro 컴포넌트입니다.

`src/components`와 마찬가지로 이 디렉터리 역시 일반적인 규칙이지만 필수는 아닙니다.

### `src/styles`

`src/styles` 디렉터리에 CSS 또는 Sass 파일을 저장하는 것이 일반적인 규칙이지만 필수는 아닙니다. 스타일이 `src/` 디렉터리 어딘가에 있고 올바르게 가져오기만 하면 Astro에서 처리하고 최적화합니다.

### `public/`

`public/` 디렉터리는 Astro 빌드 과정 중에 처리할 필요가 없는 프로젝트의 파일과 자산을 위한 곳입니다. 이 폴더의 파일은 변경 없이 빌드 폴더로 복사된 후 사이트가 빌드됩니다.

이러한 동작으로 인해 `public/`은 일부 이미지와 글꼴, 또는 `robots.txt` 및 `manifest.webmanifest`와 같은 특수 파일과 같이 처리할 필요가 없는 일반적인 자산에 이상적입니다.

`public/` 디렉터리에 CSS와 JavaScript를 배치할 수 있지만, 해당 파일은 최종 빌드에서 번들링되거나 최적화되지 않습니다.

:::tip
일반적으로 직접 작성하는 모든 CSS 또는 JavaScript는 `src/` 디렉터리에 있어야 합니다.
:::

### `package.json`

JavaScript 패키지 관리자가 의존성을 관리하는 데 사용하는 파일입니다. 또한 Astro를 실행하는 데 일반적으로 사용되는 스크립트 (예: `npm run dev`, `npm run build`)를 정의합니다.

`package.json`에는 지정할 수 있는 [두 가지 종류의 의존성](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file)이 있습니다. `dependencies`와 `devDependencies`가 그것입니다. 대부분의 경우 이들은 동일하게 작동합니다. Astro는 빌드 시 모든 의존성이 필요하며 패키지 관리자는 둘 다 설치합니다. 처음에는 모든 의존성을 `dependencies`에 넣고 특정 요구 사항이 있는 경우에만 `devDependencies`를 사용하는 것이 좋습니다.

프로젝트에 대한 새 `package.json` 파일을 만드는 데 도움이 필요하면 [수동 설정](/ko/install-and-setup/#수동-설정) 지침을 확인하세요.

### `astro.config.mjs`

이 파일은 모든 스타터 템플릿에서 생성되며 Astro 프로젝트의 구성 옵션을 포함합니다. 여기서 사용할 통합, 빌드 옵션, 서버 옵션 등을 지정할 수 있습니다.

Astro는 JavaScript 구성 파일에 대해 `astro.config.js`, `astro.config.mjs`, `astro.config.cjs`, `astro.config.ts` 등 여러 파일 형식을 지원합니다. 대부분의 경우 `.mjs`를 사용하고 구성 파일에서 TypeScript를 작성하려면 `.ts`를 사용하는 것이 좋습니다.

TypeScript 구성 파일 로딩은 [`tsm`](https://github.com/lukeed/tsm)을 사용하여 처리되며 프로젝트의 `tsconfig` 옵션을 따릅니다.

자세한 내용은 [구성 참조](/ko/reference/configuration-reference/)를 확인하세요.

### `tsconfig.json`

이 파일은 모든 스타터 템플릿에서 생성되며 Astro 프로젝트의 TypeScript 구성 옵션을 포함합니다. 일부 기능 (예: npm 패키지 가져오기)은 `tsconfig.json` 파일 없이는 편집기에서 완전히 지원되지 않습니다.

자세한 구성 설정 방법은 [TypeScript 가이드](/ko/guides/typescript/)를 참조하세요.
